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I .  INTRODUCTION 


The  past  ten  years  has  seen  much  written  on  the  improved 
methods  of  software  development*  top-down  design,  bottom-up 
testinq,  modular  decomposition*  structured  proqramminq, 
stepwise  refinement  and  other  related  subjects.  Even  more 
recently*  with  the  risinq  costs  of  maintenance*  and  the 
rapidly  increasing  functional  requirements  for  the  software 
beinq  developed*  the  need  for  excellent  documentation  of 
software  projects  has  become  apparent  with  many  articles 
addressinq  this  issue.  The  most  modern  software  development 
methodoloqies  provide  for  this  required  documentation* 
addressinq  areas  such  as  feasibility  studies,  requirements 
analysis,  proqram  performance  specifications*  test 
requirements*  commented  code*  data  flow  diaqrams*  data 
die t ionar ies «  interface  specifications*  and  the  like.  A 
major  purpose  of  these  methodoloqies  is  to  allow  software 
developed  by  multiple  people  to  stand  independent  of  the 
individual.  That  is*  to  provide  a  method  that  captures  the 
process  used  and  the  product  produced  by  a  qroup  of 
individuals  in  a  manner  such  that  another  qroup  of 
individuals  may  understand  the  product  produced  and  the 
process  used  to  produce  it  without  requiring  further 


communication  with  the  original  qroup 


The  Navy*  with  its  extremely  automated  combat  and 
enqineerinq  systems  is  like  any  other  software 
produc inq/consuminq  firm  and  is  one  of  the  larqest  in  the 
cateqory  of  tactical  real-time  systems  and  enqineerinq 
control  systems.  With  software  development  and  maintenance 
costs  of  naval  tactical  systems  totalinq  in  the  billions  of 
dollars  annual ly,  even  a  relatively  small  improvement  in 
software  development  efficiency  has  an  immense  potential  for 
a  siqnificant  reduction  in  the  cost  of  a  system’s 
development.  As  a  consequence*  the  Navy  has  continually 
updated  their  Military  Standards  for  Software  Development 
( DOD-STD— 1679A) . 

This  thesis  compares  the  recommended  software 
development  methodo loqies  of  the  commercial  and  academic 
fields*  and  those  recommended  by  the  National  Bureau  of 
Standards  with  those  presently  in  use  by  the  Navy.  The  main 
emphasis  is  on  the  documents  qenerated  in  these 
methodoloqies  and  the  documentation  process. 

In  this  thesis  the  term  "software"  will  be  used  as 
defined  by  Fairley  CRef.  l:p.  61  to  mean  the  source  code  and 
all  the  associated  documents  and  documentation  that 
constitute  the  software  product.  Requirements  documents* 
desiqn  specifications*  source  code*  test  plans*  quality 
assurance  and  conf iqurat ion  manaqement  procedures*  software 
trouble  reports*  etc.*  all  constitute  components  of  the 
software  product  and  are  included  in  the  term  "software". 


"Documentation"  will  be  defined  as  a  description  of  the 
characteristics  of  an  entity  or  process  recorded  for  the 
purpose  of  transferring  information  about  that  entity  or 
process.  For  the  purposes  of  this  thesis  "documentation" 
will  also  include  descriptions  of  intent  or  requirements 
such  as  the  information  within  a  computer  proqram 
development  plan*  or  a  proqram  requirements  specification. 

The  term  "documentation  process"  will  refer  to  the 
methodoloqy  used  to  collect  and  explain  the  associated 
characteristics. 

The  term  "documentation  levs1, ",  or  level  of 
documentation  will  refe>~  to  the  amount  of  detailed 
information  the  documentation  records  about  the  entity  or 
process  in  relation  to  the  total  amount  of  information  that 
ever  was  available  about  the  entity  or  process.  The  more 
information  recorded  in  the  documentation,  the  hiqher  the 
level  of  the  documentation. 

"Document"  will  refer  to  the  instrument  used  to 
transport  the  documentation  from  one  individual  to  another, 
or  from  one  qroup  of  individuals  to  another.  Documents  are 
produced  to  provide  a  medium  with  which  documentation  can  be 
transferred . 

In  the  process  of  writinq  this  thesis,  interviews  were 
conducted  with  various  key  individuals  experienced  in  Navy 
surface  tactical  embedded  computer  system  desiqn  projects. 
These  interviews  were  non-statistical  in  nature.  The  purpose 


of  these  interviews  was  to  provide  experienced  opinions  and 
feelinqs  on  problems  and  causes  evident  in  past  and  present 
development  efforts.  Additionally!  this  thesis  only  views 
those  practices  in  use  in  the  Naval  Sea  Systems  Command! 
other  commands  within  the  Navy  may  have  different 
definitions  and  methodo 1 oq i es .  This  thesis  is  not  meant  to 
apply  to  those  commands. 

The  DDG-51  (AEGIS  class  destroyer)  combat  system  desiqn 
effort  was  used  as  the  example  software  development  project. 
This  particular  project  was  chosen  because  it  reflects  the 
efforts  of  an  experienced  desiqn  team  (many  of  the  team 
members  were  associated  with  the  CG-47  desiqn  effort ),  and 
has  adequate  fundinq.  Additionally!  this  project  is 
relatively  new  (the  computer  proqram  development  plan  was 
printed  in  January  1985)  and  had  the  opportunity  to  take 
advantaqe  of  the  latest  software  desiqn  methodo loq ies . 

Chapter  II  presents  suqqested  documentation  requirements 
of  the  National  Bureau  of  Standards  and  introduces  a  typical 
software  life-cycle.  Chapter  III  explains  the  Navy’s 
tactical  software  life-cycle  and  the  documentation 
requirements  of  DOD-STD- 1 679A  (Navy).  Chapter  IV  compares 
the  Navy’s  standards  with  those  recommended  in  the 
commerc ia 1 /academic  field  and  attempts  to  offer  solutions  to 
documentation  problems  expressed  to  be  evident  in  Naval 
tactical  software  development.  Chapter  V  summarizes  th 


This  section  defines  "software  enqineer inq"  as  used  in 
this  thesis  and  introduces  the  software  life-cycle  concept 
by  describing  three  models  sometimes  used  to  represent 
different  concepts  of  the  software  life-cycle.  This  section 
also  presents  some  document  and  documentation 
recommendations  throuqh  the  use  of  the  life-cycle  models 
they  are  associated  with,  and  presents  the  qoals  or 
reasoninq  behind  the  technical  documentation  process  and  the 
documents  produced. 

A.  THE  SOFTWARE  LIFE-CYCLE 

Barry  Boehm  CRef.  2:p.  163  defines  software  enqineerinq 
as  "the  application  of  science  and  mathematics  by  which  the 
capabilities  of  computer  equipment  are  made  useful  to  man 
via  computer  proqramsi  procedures,  and  associated 
documentation".  Fairley  CRef.  l:p.  23  defines  software 
enqineerinq  as  "the  technological  and  managerial  discipline 
concerned  with  systematic  production  and  maintenance  of 
software  products  that  are  developed  and  modified  on  time 
and  within  cost  estimates". 

Within  the  context  of  this  thesis  it  is  sufficient  to 
define  software  enqineerinq  to  be  the  technological  and 
managerial  discipline  concerned  with  the  systematic 


production  and  maintenance  of  software  keepinq  in  mind  that 
softwarei  as  defined  earlier*  includes  the  source  code  and 
all  associated  documents  and  documentation  that  constitute 
the  software  product. 

Experience  in  software  enaineerinq  has  tauqht  us  that  it 
is  extremely  important  at  the  start  of  every  software 
project  to  develop  a  model  of  the  life-cycle  of  the 
particular  software  product.  As  Fairley  states  CRef.  l:p. 
373:  "A  life-cycle  model  that  is  understood  and  accepted  by 
all  concerned  parties  improves  project  communication  and 
enhances  project  manaqeab i 1 i ty *  resource  allocation*  cost 
control*  and  project  quality." 

The  model  must  be  developed  specifically  for  the  project 
at  hand*  however  many  qeneric  models  are  available*  that 
with  minor  modifications  are  usually  well  suited  for  the 
software  project. 

Perhaps  the  most  basic  model  and  the  most  traditional  is 
the  phased  life-cycle  model  often  described  with  the 
waterfall  chart  of  Fiqure  1.  Introduced  in  the  early  70’s, 
but  conceptually  existant  in  the  mid  60’s  CRef.  2:pp.  35- 
383*  the  phased  life-cycle  model  seqments  the  life  cycle 
into  a  series  of  successive  steps  or  phases.  Each  phase 
requires  a  well  defined  input*  utilizes  a  well  defined 
process*  and  results  in  a  well  defined  output  that  is  used 
as  the  startinq  point  for  the  subsequent  phase. 


feasibility 


Software  plans  and 
requirements 


Integrator 


^  Product 
verification 


Operations  and 


Revainlat'on  I 


Fiqure  1:  Waterfall  Model  of  the  Software  Life-cycle 

CRef.  2sp.  363 

The  various  phases  of  the  phased  life-cycle  model  are: 

1.  System  Feasibility.  Defininq  a  preferred  concept  for 
the  software  product*  and  determininq  its  life-cycle 
feasibility  and  superiority  to  alternative  concepts. 


2.  Software  Plans  and  Requirements.  A  complete*  validated 
specification  of  the  required  functions*  interfaces* 
and  performance  standards  for  the  software  product. 


3.  Product  Desiqn.  A  complete,  verified  specification  of 
the  overall  hardware-software  architecture*  control 
structure*  and  data  structure  for  the  product*  alonq 
with  such  other  necessary  components  such  as  draft 
user’s  manuals  and  test  plans. 

4.  Detailed  Desiqn.  A  complex*  verified  specification  of 
the  control  structure*  data  structures*  interface 
relations*  sizinq*  key  alqorithms*  and  assumptions  for 
each  proqram  component. 

3.  Codinq.  A  complete*  verified  set  of  the  proqram 
components . 

6.  Inteqration.  A  properly  functioninq  software  product 
composed  of  the  software  components. 

7.  Implementation.  A  fully  functioninq  operational 
hardware-software  system*  includinq  such  objectives  as 
proqram  and  data  conversions*  installation  and 
traininq . 

8.  Maintenance.  A  fully  functioninq  update  of  the 
hardware-software  system.  This  subqoal  is  repeated  for 
each  update/  modification. 

An  important  aspect  of  the  phased  life-cycle  model  is 
that  each  phase  ends  with  verification  or  validation. 
Validation  as  it  is  used  here  means  to  make  a  dedicated 
effort  to  ensure  the  product  of  the  phase  is  actually  what 
was  intended  to  be  produced  at  the  beqinninq  of  the  phase. 
Informally*  validation  is  "Are  we  buildinq  the  riqht 
product?".  Verification  as  it  is  used  here  refers  to  a 
dedicated  effort  to  ensure  that  the  product  or  output  of  the 
phase  is  correct  for  the  input  of  the  phase;  Informally, 
verification  is  "Are  we  buildinq  the  product  riqht?".  In  a 
development  desiqn  such  as  the  phased  life-cycle  model  that 
relies  stronqly  on  the  output  from  one  phase  as  the  input  to 


the  next  phase,  the  determination  of  the  correctness  of  the 
output  before  it  is  used  as  input  is  vital  to  the  process. 
Verification  and  validation  are  planned  conscientous  efforts 
to  eliminate  errors  within  the  development  process. 

There  are  many  critics  of  the  phased  life-cycle 
approach.  Amonq  their  complaints  is  that  the  approach  does 
not  accurately  reflect  the  actual  software  development 
process,  that  it  does  not  reflect  the  interaction  and 
overlap  between  phases  CRef.  l:p.  411.  Nor  does  the  phased 
life-cycle  approach  provide  for  prototypes,  or  enhancement 
methods.  Additionally,  if  an  error  is  made  in  the  early 
staqes,  and  is  missed  in  the  oriqinal  validation,  the  error 
will  not  be  evident  until  the  final  validation  is  made  after 
the  system  is  implemented.  The  phased  life-cycle  approach 
does  not  provide  a  means  to  alter  a  project’s  desiqn  once 
the  implementation  phase  is  reached  without  a  very  expensive 
repetition  of  the  previous  phases.  Consequently,  if  a  fatal 
problem  is  uncovered  in  the  validation  portion  of  the 
implementation  phase  of  the  phased  life-cycle  approach  it  is 
very  expensive  to  correct. 

The  beauty  of  the  phased  life-cycle  approach  is  its 
simplicity.  The  model  is  easy  to  understand,  easy  to 
represent,  and  allows  for  the  definition  of  specific 
milestones  even  if  they  are  hard  to  reach  in  actual 


pract ice 


Another  software  life-cycle  model  is  the  Prototype  Model 
shown  in  Fiqure  2.  The  model  emphasizes  the  source  of 
product  requests*  the  major  qo/no-qo  decision  points,  and 
the  use  of  prototypes.  A  prototype  is  a  model  or  a  mockup  of 
the  software  product.  In  contrast  to  a  simulation  model,  the 
prototype  model  exhibits  components  of  the  actual  product 
althouqh  normally  at  reduced  capability  or  performance 
standards  CRef.  lsp.  493.  Prototypinq  allows  desiqners  to 
explore  various  technical  issues  and/or  to  allow  the  qradual 
development  of  requirements  and  performance  specifications. 


Fiqure  2s  The  Prototype  Software  Life-cycle  Model  CRef. 


The  approach  is  useful  when  there  is  not  a  clean  set  of 
system  requirements  and  the  possibility  of  system 
requirements  chanqinq  is  hiqh.  Prototypes  are  desiqned  to 
allow  experimentation  and  chanqe  without  the  expense  of  full 
implementation!  and  to  inexpensively  identify  the  errors 
normally  present  in  the  first  attempt  to  develop  a  system. 

Critics  of  the  prototypinq  method  cite  the  "Let's  qo 
with  the  prototype"  attitude  that  never  develops  the  full 
systemt  or  the  expense  involved  with  larqer  systems  of 
buildinq  the  system  twice.  However (  when  developinq  a  new 
system  from  the  beqinninq(  some  form  of  prototypinq  is 
usually  desirable. 

Yet  another  life-cycle  model  is  the  iterative 
enhancement  model.  In  this  model  each  version  is  a  complete 
system  that  performs  useful  work.  Enhancements  are  made  to 
the  previous  system  to  add  new  capabilities  as  required. 

Some  minor  redesiqn  of  the  previous  system  may  occur  to 
correct  desiqn  deficiencies  evident  in  the  previous  system; 
however(  the  majority  of  chanqe  is  in  the  form  of  system 
enhancements . 

As  stated  earlierf  different  models  exist  for  different 
kinds  of  projects.  Each  emphasizes  different  aspects  of  the 
software  life-cycle>  and  in  many  cases  more  than  one  type  of 
model  is  combined  to  allow  the  development  of  a  model 
specifically  tailored  to  the  project  at  hand.  The  most 


important  idea  to  be  captured  is  the  need  for  a  life-cycle 
model.  Such  a  model  should  encompass  all  the  activities 
required  to  define,  develop,  test,  deliver,  operate,  and 
maintain  a  software  product.  Many  models  recommend  specific 
documents  be  produced  at  different  phases  to  contain  the 
documentation  suqqested  for  that  phase.  No  sinqle  model  is 
appropriate  for  all  software  products.  However  defininq  a 
model  early  on  in  the  product  development  and  identify inq 
the  planned  documents  to  be  produced  is  essential  to  the 
product’s  success. 

The  next  section  will  view  some  recommended  documents 
and  the  documentation  contained  in  these  documents  as  a 
function  of  the  life-cycle  phases. 

B.  DOCUMENTATION  WITHIN  THE  SOFTWARE  LIFE-CYCLE 

Computer  proqrams  evolve  in  phases  from  the  time  that  an 
idea  to  create  or  modify  software  occurs  throuqh  the  time 
that  the  software  enqineerinq  process  produces  the  required 
output.  Usinq  the  terminoloqy  defined  in  the  National  Bureau 
of  Standards  Federal  Information  Processinq  Standards  (NBS 
FIPS)  publications  CRef.  31,  the  three  major  phases  of  the 
software  project  are:  the  initiation  phase,  the  development 
phase,  and  the  operation  phase.  The  three  phases,  alonq  with 
their  associated  sub-phases  and  suqqested  documentation 
documents  are  shown  in  Fiqure  3.  This  thesis  is  concerned 


with  the  suqqeated  documentation  collected  durinq  these 
phases . 
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Fiqure  3.  Documentation  Within  the  Software  Life-cycle  [Ref 
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Pro iect  Request  Document.  The  purpose  of  this  document 
is  to  provide  the  means  for  a  user  orqanization  to  request 
the  development*  procurement*  or  modification  of  software. 
It  serves  as  the  initiatinq  document  in  the  software  life- 
cycle,  and  provides  a  basis  for  communication  with  the 
requestinq  orqanization  to  further  analyze  requirements  and 
assess  impacts.  This  document  is  quite  often  embedded  in 


another  document  as  a  part  of  a  larqer  system. 


Feasibility  Study  Document.  The  purpose  of  the 
feasibility  study  document  is  to  provide:  (1)  an  analysis  of 
objectives*  requirements  and  concepts;  (S)  to  evaluate 
alternative  approaches;  and  (3)  to  identify  the  proposed 
solution  and  the  justifyinq  arquments  that  make  this  the 
most  attractive  alternative  .  This  document*  combined  with 
the  cost/benefit  analysis  document*  should  provide 
manaqement  with  the  required  information  to  make  an  informed 
decision  on  whether  or  not  to  continue  the  project. 

Cost/Benefit  Analysis.  The  purpose  of  this  document  is 
to  provide  manaqers*  users*  desiqners*  and  auditors  with 
adequate  cost  and  benefit  information  to  analyze  different 
alternatives  from  the  standpoint  of  the  cost  and  benefit 
tradeof fs . 

Functional  Requirements  Document.  The  purpose  of  this 
document  is  to  provide  a  basis  for  a  mutual  understand inq 
between  all  concerned  parties  about  the  results  of  the 
initial  definition  staqe  of  the  software*  includinq  the 
requirements*  operatinq  environment,  and  development  plan. 

Data  Requirements  Document.  The  purpose  of  this  document 
is  to  provide*  durinq  the  definition  staqe*  a  data 
description  and  technical  information  about  data  collection 
requirements . 

Svstem/Subsvstem  Specification.  The  purpose  of  this 
document  is  to  specify  for  analysts  and  proqrammers  the 


requirements,  operatinq  environment,  desiqn  characteristics* 


and  proqram  specifications  (if  desired)  for  a 
system/subsystem . 

Program  Specification.  The  purpose  of  this  document  is 
to  specify  for  programmers  the  requirements*  operating 
environment,  and  design  characteristics  of  the  computer 
program . 

Data  Base  Specification.  The  purpose  of  this  document  is 
to  specify  the  identification,  logical  characteristics,  and 
physical  characteristics  of  a  particular  database. 

User’s  Manual.  The  purpose  of  this  document  is  to 
sufficiently  describe  the  functions  performed  by  the 
software  in  a  fashion  that  all  users  of  the  system  might  be 
able  to  understand  (that  is  it  uses  non-ADP  terminology). 

Operations  Manual.  The  purpose  of  this  document  is  to 
provide  computer  operations  personnel  with  a  description  of 
the  software  and  of  the  operational  evironment  so  that  the 
software  may  be  run  properly. 

Proqram  Maintenance  Manual.  The  purpose  of  this  manual 
is  to  provide  the  maintenance  programmer  with  the 
information  necessary  to  understand  the  proqrams,  their 
operating  environment,  and  their  maintenance  procedures. 

This  includes  a  listinq  of  the  code  or  instructions  on  how 
to  obtain  a  listing. 

Test  Plan.  The  purpose  of  this  document  is  to  provide  a 
plan  for  the  testing  of  software;  detailed  specifications. 


descriptions,  and  procedures  for  all  tests,  and  test  data 
reduction  and  evaluation  criteria. 

Test  Analysis  Report.  The  purpose  of  this  document  is 
to  record  and  analyze  test  results  and  findinqs. 
Deficiencies  and  capabilities  are  presented  for  review  and 
provide  a  basis  to  determine  software  readiness  for 
imp lementat ion . 

The  next  section  will  describe  the  reasoninq  behind 
recommendinq  all  these  documents  and  the  documentation 
contained  within  them. 

C.  TECHNICAL  DOCUMENTATION  GOALS 

The  purpose  of  qood  technical  documentation,  that 
documentation  which  deals  with  for  example,  proqram 
requirements,  proqram  desiqn,  interfaces,  data  requirements 
alqorithms,  structures,  etc.,  can  be  summarized  in  one 
phrase;  to  accommodate  chanqe  at  a  reasonable  cost. 
Furthermore  the  documents  which  contain  this  documentation 
provide  definitive  work  products  to  be  produced  in  each 
phase  of  the  life-cycle.  If  a  project  were  to  meet  all  of 
its  requirements  and  specifications  durinq  the  testinq 
phase,  to  maintain  the  same  individuals  throuqhout,  and  to 
face  a  completely  static  environment  for  its  entire  life- 
cycle,  then  documentation  on  how  it  performed  its  functions 
would  be  absolutely  worthless  after  completion  of  the 
project  except  to  the  curious.  However  this  is  most  always 


never  the  case.  The  foreword  to  DQD-STD- 1679A  (Navy)  CRef. 


4 : p .  iiiD  states  three  major  factors  in  the  design  and 
documentation  of  Navy  tactical  programs.  These  are: 


Criticality  of  Performance.  The  combat  capability  of 
defense  systems  and  the  combat  survivability  of  combatant 
units  of  the  operating  forces  depend,  in  part,  upon  the 
effective  operation  of  the  software.  Therefore,  careful, 
persistent  management  must  be  exercised  in  the  software 
development  phase  to  ensure  maximum  reliability  and 
maintainabi 1 ity . 

Changing  Operational  Reguirement.  Software  implements 
system  operations  and  doctrine  in  areas  susceptible  to 
many  changes  of  performance  reguirements  and 
spec  if icat ions .  These  changes  often  impact  the  software 
and  need  expeditious  implementation.  This  demands  that 
software  be  designed  to  facilitate  efficient  change, 
sometimes  at  the  expense  of  technical  design  efficiency. 
Designers  must  continously  consider  the  tradeoffs  between 
future  modifiability  of  the  product  and  design  efficiency 
as  the  reguirements  now  exist.  Continuation  of  an 
efficient  change  capability  over  the  operational  life  of 
the  system  also  reguires  detailed  documentation 
describing  the  system  and  the  software.  Proposed  changes 
and  their  total  impact  must  be  easily  discernible  and 
must  be  capable  of  being  implemented  by  personnel  not 
associated  with  the  original  development  effort. 

Life-cycle  Cost.  Development  and  implementation  of 
changes  to  the  software  over  the  operational  life  of  the 
system  are  costly.  The  design  of  the  software  during 
development  must  be  strongly  influenced  by  factors  which 
will  reduce  life-cycle  costs. 

That  the  underlying  goal  of  any  documentation  is  to 
provide  communication  of  the  characteristics  of  a  system  and 
the  processes  used  in  developing  the  system  independant  of 
individuals,  is  apparent  from  the  foreword  to  D0D-STD-1679A 
(Navy)  and  other  publications.  Technical  documentation  must 
anticipate  change  in  the  programs.  Enough  information, 
through  flowcharts,  listings,  data  dictionaries,  etc.,  must 


be  available  to  persons  not  associated  with  the  oriqinal 
desiqn  qroup  to  allow  them  to  develop  an  understand inq  of 
what  the  proqram  does  and  how  it  does  it. 

The  next  section  will  discuss  the  Navy’s  methods  for 
providinq  this  technical  documentation  as  prescribed  by  DOD- 
STD-1679A(Navy )  and  interpreted  by  the  DDG-51  Combat  System 
Software  Development  Project. 


Ill 


NAVY  TECHNICAL  DOCUMENTATION 


As  is  mads  apparent  in  the  previous  sections*  excellent 
documentation  is  an  important  portion  of  any  software 
project.  This  requirement  holds  true  for  Navy  software 
projects  as  well  where  a  major  consideration  of  the  project 
is  to  plan  for  chanqe.  This  section  presents  a  description 
of  the  navy  tactical  software  life-cycle  as  described  in 
D0D-STD-1679A<Navy )  and  presents  the  planned  documentation 
in  an  example  Navy  software  project  by  describinq  the 
planned  documents  to  be  produced  in  each  phase  of  the 
1 ife-cycle. 

A.  THE  NAVY  TACTICAL  SOFTWARE  LIFE-CYCLE 

"The  software  challenqe  is  to  control  the  desiqn  process 
for  a  complex  of  operational  computer  proqrams  so  that  the 
resultinq  products  can  be  inteqrated  into  a  reliable* 
maintainable*  and  survivable  combat  system  fully  responsive 
to  the  mission  requirements"  CRef.  53.  This  is  the  openinq 
paraqraph  to  the  DDG-51  Computer  Proqram  Development  Plan. 

It  is  like  the  challenqe  of  any  major  software  undertakinq* 
with  the  exception  that  the  possibility  of  further  chanqe* 
modifications*  and  enhancements  is  much  qreater*  and  that 
the  software  project*  beinq  a  qovernmental  project*  will 
always  be  under  close  scrutiny.  The  Navy  tactical  software 


life-cycle  is  very  much  like  the  phased  life-cycle  described 


earlier  with  staqes  very  similiar  to  those  described  in  NBS 
FIPS  Publications  38  and  64.  Usinq  the  Aeqis  Shipbuildinq 
Proqram,  DDG  51  Computer  Proqram  Development  Plan*  as  an 
example  of  the  typical  tactical  software  development  plant 
one  can  see  in  Fiqure  4  the  five  phases  described  in  the 
development  plan. 


-  System  Definition  and  Design  Phase*.  This  is  a 
predecessor  phase  in  which  the  functional  baseline  is 
established  in  the  A  level  spec  if icat ion ,  which  is  a 
formalization  of  the  top  level  requirements  of  the 
system.  And  the  first  level  of  the  allocated  baseline  is 
created  and  recorded  in  the  element  B1  specification, 
which  is  the  breakdown  of  the  A  level  specification  into 
loqical  elements  such  as  the  radar  element  . 

-  Computer  Program  Definition  and  Design  Phase.  This  phase 
encompasses  the  definition  of  the  computer  proqram 
performance  requirements,  the  establishment  of  interface 
requirements,  and  the  specification  of  the  software  top 
-level  desiqn.  The  performance  requirements,  documented 
in  the  Proqram  Performance  Specification  <PPS>,  are  the 
drivinq  force  far  every  subsequent  phase  of  the  computer 
proqram  development  process  from  desiqn  throuqh  testinq 
and  delivery. The  requirements  incorporated  in  this 
document,  alonq  with  preliminary  interface  definitions 
and  early  top  level  software  desiqn  considerations,  are 
reviewed  by  the  Navy  at  the  Preliminary  Desiqn  Review 

( PDR )  which  serves  to  present  the  PPS  for  approval  as 
the  preliminary  allocated  baseline  for  further 
development.  Based  on  the  approved  PPS,  the  finalized 
interface  requirements  and  the  top-level  proqram  desiqn 
are  developed  and  documented,  respectively,  in  the 
Interface  Desiqn  Specification  (IDS)  and  the  Proqram 
Desiqn  Specification  <PDS).  The  Critical  Desiqn  Review 


4The  DDG-51  software  project  is  a  Naval  Sea  Systems 
Command  project.  However,  the  vast  majority  of  the  project 
is  performed  throuqh  a  contract  with  RCA  and  various 
subcontractors.  Some  Navy  projects  are  developed  totally 
"in-house",  however  the  normal  procedure  is  to  issue 
contracts  for  the  actual  software  development. 
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(CDR)  provides  the  mechanism  for  Navy  review  and 
approval  of  these  documents.  This  completes  the  desiqn 
phase  of  computer  proqram  development  process*  and  these 
documents  serve  as  the  approved  final  allocated  baseline 
for  further  development. 

Computer  Prooram  Implementation  Phase.  The  computer 
proqram  implementation  phase  is  based  on  the  approved 
documents  and  specifications  produced  in  the  desiqn 
phase.  The  implementation  phase  encompasses  the  detailed 
desiqn  of  the  proqram  modules  and  data  basje  as  well  as 
the  codinq  and  debuqqinq  of  these  items.  The  proqram 
module  loqical  desiqns  and  the  detailed  data  base 
desiqns  are  developed  and  documented*  respect ively *  in 
preliminary  Proqram  Description  Documents  (PDDs)  and  the 
Data  Base  Desiqn  Documents  (DBD).  These  documents  are 
reviewed  at  Informal  Desiqn  Reviews*  in  which  the  Navy 
participates*  and  which  serves  to  provide  approval  of 
the  detailed  desiqn  and  authorization  to  proceed  with 
codinq.  Once  codinq  is  completed  and  error  free  compiles 
of  the  modules  and  data  base  are  achieved*  an  internal 
structured  walk-throuqh  of  the  implemented  code  is 
undertaken  to  assure  compliance  with  desiqn 
requirements.  Successful  completion  of  this  structured 
walk-throuqh  serves  to  release  the  modules  and  the  data 
base  for  testinq.  This  completes  the  implementation 
phase. 

Computer  Program  Testinq  Phase.  Computer  Proqram 
development  te  stinq  is  performed  within  the  context  of 
the  top-down  approach  to  development.  Testinq  starts 
with  the  smallest  operatinq  components*  i.e.*  modules* 
and  develops  throuqh  successively  more  complex  and 
inclusive  staqes.  Nodules  are  integrated  into  subprogram 
builds*  which  are  operational  subsets  of  the  complete 
computer  proqram.  Build  tests  are  performed  with  Navy 
participation.  Functional  capabilities  are  added  to  the 
subprogram  builds*  and*  in  the  last  staqe*  the  final 
build  is  tested  as  a  complete  computer  proqram.  Test 
plans*  test  procedures*  and  test  reports  are  prepared  at 
all  levels  of  testinq*  beqinninq  with  the  module  unit 
testinq.  The  Computer  Proqram  Qualification  Test* 
conducted  at  the  developer  computer  proqram  test 
facility  and  performed  to  Navy  approved  test  procedures* 
is  the  final  test  of  the  computer  proqram  as  a 
standalone  entity.  The  successful  accomplishment  of  this 
test  marks  the  completion  of  the  software  development 
phase.  Subsequent  activity  is  in  support  of  element  and 
system  level  integration  and  testinq.  A  preliminary 
product  baseline  is  established  at  the  completion  of  the 
software  testinq  phase. 


System  Integration  Testing  Phase.  At 
Engineering  Development  (CSED)  site* 
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Figure  5  shows  the  similarities  between  the  Navy’s 
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phased  life-cycle  and  the  NBS  phased  life-cycle  by 
displaying  the  five  main  phases  of  naval  tactical  software 
and  the  phases  recommended  by  the  National  Bureau  of 
Standards.  Also  shown  is  the  suggested  documents  to  be 
produced  during  these  phases. 

The  concept  of  documentation  reguirements  for  the  Navy 
is  contained  in  D0D-STD-1679A,  however  the  actual  document 
reguirements,  and  the  specific  contents  of  each  document, 
along  with  the  prescribed  layout  of  the  document  is 
prescribed  in  a  data  item  description  (DID).  These  DIDs  are 
envoked  in  a  contract  as  necessary,  to  ensure  standardized 
and  complete  documentation  is  included  in  the  software 
package  and  to  provide  the  flexibility  to  tailor  DOD-STD- 
1679A(Navy)  to  various  software  projects.  The  documentation 
reguirements  and  the  documents  to  be  produced  in  Naval 
tactical  software  development  is  discussed  in  the  next 
section. 

B.  NAVAL  SOFTWARE  TECHNICAL  DOCUMENTATION  REQUIREMENTS 

As  stated  before,  the  content,  style,  and  coverage  of 
all  documentation  associated  with  a  naval  software  contract 
is  well  defined  in  the  contract.  The  "Contract  Data 
Reguirements  List",  or  CDRL,  specifies  which  military 
standard  the  contract  shall  conform  to.  The  military 
standard,  MIL-STD- 1679A  (Navy)  in  this  case,  is  not  simply  a 

31 


■  .S# .  -X .  .  ft. .. m 


guideline,  it  is  much  stronger.  A  standard  must  be  complied 


with,  and  qenerally  provides  the  "shalls"  of  a  contract,  or 
the  qeneral  areas  that  must  be  addressed  throuqh  the 
documentation.  Also  included  in  the  CDRL  are  "data  item 
descriptions",  or  DIDs,  which  specify  exactly  how  a  document 
will  appear,  and  exactly  what  this  document  will  contain. 

The  standard  provides  the  requirements  in  qeneral  terms,  and 
the  DIDs  provide  the  specifics  for  a  particular  contract. 
DIDs  provide  the  flexibility  to  tailor  a  military  software 
contract  to  any  project,  be  it  larqe  or  small. 

The  best  way  to  understand  the  documentation  required  in 
a  military  software  project  is  to  view  it  as  a  it  is  to  be 
recorded  durinq  the  life-cycle. 

-  Initial  Planning  Software  Development  Phase; 

-  Objectives: 

1.  To  combine  the  Navy’s  and  contractor’s  ideas 
for  accomplishing  the  project. 

-  Documentation: 

-  Software  Development  Plan.  Software  management’s 
plan  for  developing  the  proqram  performance 
specifications,  and  producing  the  software. 

-  Software  Configuration  Management  Plan .  The 
configuration  management  group’s  plan  for 
managing  changes  in  software  configuration 


during  software  development 


qroup’s  plan  for  verifying  that  all  requirements 


in  the  contract  are  met.  The  basis  for  the  test 
plan . 


-  Objectives: 


1.  To  identify  the  Computer  Proqram  Configuration 
Items  (CPCIs)  required  for  each  element. 

2.  To  determine  the  detailed  proqram  performance 
requirements  for  each  combat  system  element 
computer  proqram  and  to  specify  them  in  the 
element  Proqram  Performance  Spec i f icat ion  (PPS) 

3.  To  define  the  interface  desiqn  requirements  and 
to  specify  them  in  the  Interface  Desiqn 
Specification  (IDS). 

4.  To  define  the  operatinq  system  and  support 
proqrams  required  to  support  the  operational 
element  proqrams  and  the  development  process. 

5.  To  provide  desiqn  information  to  the  Navy, 
system  desiqners,  and  other  enqineerinq 
aqents . 

6.  To  reduce  risk  by  establishing  the  technical 
feasibility  of  the  Combat  System  Software. 


7.  To  identify  critical  areas  early  in  the 


T 


software  development  cycle. 

S.  To  provide  for  quality  assurance  and  testinq 
requirements. 

Process : 

This  functional  baseline  established  durinq  the 
system  definition  and  desiqn  phase  includes  the 
element  Prime  Item  Development  specification  (Bl) 
which  provides  the  vehicle  for  mappinq  the 
functions  allocated  to  computer  proqrams  into 
computer  proqram  performance  requirements. 

Fiqure  6  shows  the  process  used  in  determininq 
these  computer  proqram  performance  requirements. 
The  resultinq  definition  of  element  computer 
proqram  requirements  is  documented  in  the 
PPS  for  each  element*  the  preliminary  Interface 
Desiqn  Specification  (IDS),  and  the  Desiqn 
Disclosure  Packaqe  (DDP).  These  documents  form 
the  basis  for  the  Preliminary  Desiqn  Review  (PDR). 
Documentation: 

-  Proqram  Performance  Specification.  For  each 
element  the  PPS  provides  the  baseline  document 
for  subsequent  computer  proqram  development. 

It  defines  the  operational  and  functional 
performance  required  of  the  element  computer 
proqram*  and  provisions  for  quality  assurance 
and  testinq.  The  PPS  also  specifies  a  computer 
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equipment  configuration  desiqned  to  satisfy 
the  specified  requirements. 
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Fiqure  6.  Computer  Proqram  Definition  and  Desiqn  Phases 

[Ref .  5 : p .  3-4 3 

-  Interface  Design  Spec i f i ca 1 1 on ( s  )  .  The 
preliminary  IDS  provided  the  definition  of  all 
diqital  interfaces  to  the  element  computer 
proqram . 

-  Desiqn  Disclosure  Package.  The  DDP  provides  the 


results  of  modeling,  system  engineering  analysis 


and  any  other  studies  done  to  determine  system 


feasib i 1 i ty . 

Computer  Program  Design  Phase 
Ob  ject ives : 

1.  To  develop  the  computer  proqram  architecture  and 
top-level  desiqn  and  to  specify  it  in  the  Proqram 
Desiqn  Spec i f icat ion  (PDS)  for  each  element. 

E.  To  specify  module  functional  descriptions* 
proqram  control  loqic,  hiqh-level  data  base 
desiqn,  and  initial  memory  and  time  resource  budqet 
requirements . 

3.  To  develop  detailed  definition  of  computer  proqram 
interfaces,  and  to  specify  these  in  computer 
proqram  interface  desiqn  specifications  (IDSs). 
Process : 

Followinq  the  approval  of  the  PPS  for  an  element 
computer  proqram,  an  element  Proqram  Desiqn 
Specification  (PDS)  is  developed  to  specify  the 
arch i tectural  and  top-level  desiqn  requirements 
for  the  element  computer  proqram.  The  computer 
proqram  desiqn  process  involves  the  allocation 
of  software  functions  defined  in  the  PPS  to 
software  tasks,  as  shown  in  fiqure  7.  Some  of  the 
functions  to  be  performed  durinq  this  phase  are: 

-  A  functional  allocation  of  all  performance 


requirements  shall  be  made  to  the  computer 


1 

.  ■ 

* 


proqram  modules. 

-  A  functional  flow  of  proqram  data  and  control 
shall  be  defined  in  all  modes  of  operation. 

-  The  proposed  architecture  shall  be  verified  as  to 
its  capabilities  to  support  the  maximum 
computational  load. 

-  A  common  data  base  shall  be  desiqned  for  all  data 
elements  used  by  two  or  more  subproqrams. 


Fiqure  7.  Computer  Proqram  Desiqn  Process  CRef.  5:p.  3-63 


Documentation 


-  Program  Design  Specification.  The  PDS  is  generated 
according  to  the  reguirements  and  constraints  laid 
down  by  the  PPS.  At  this  stage*  the  development 
process  focuses  on  a  top-down  translation  of  system 
operational  function  requirements  into  proqram 
loqic  including  module  functional  descriptions* 
proqram  control  loqic*  and  memory-and-t iminq 
estimates.  Such  items  are  necessary  for  detailed 
subprogram  and  data-base  desiqn  and 
implementation.  Included  are  proqram  functional 
flow  diaqramst  cross  reference  tables  between 

the  PPS  and  the  PDS*  the  modular  proqram 
structure,  and  the  proqram  data  flow  diaqram. 

-  Interface  Desiqn  Specification.  The  preliminary 
IDS(s)  produced  durinq  the  definition  phase  are 
updated*  and  the  details  of  interfaces  (messaqes) 
are  added.  This  document,  after  approval  at  the 
Critical  Desiqn  Review*  is  placed  under 

conf iqurat ion  control.  This  document  provides  a 
detailed  description  of:  all  data  units*  all 
messaqes*  and  all  control  siqnals. 

-  Data  Base  Design  Document.  A  DBD  is  produced  for 
each  element.  The  DBD  provides  a  complete  detailed 
description  of  all  common  data  items  necessary  to 


carry  out  the  element  computer  proqram  functions. 
Common  data  are  those  required  by  two  or  more 
modules.  This  document  is  completed  durinq  the 
next  phassi  i.e.i  the  implementation  phase. 

Durinq  the  detailed  desiqn  portion  of  the 
implementation  phase,  an  element  computer 
proqram  data  base  librarian  maintains  the 
the  developinq  data  base  in  the  form  of  the  DBD. 
Usinq  the  DBD  in  the  role  of  Conf iqurat ion 
Manaqsment,  the  DBD  serves  .he  purpose  of  (1) 
Controllinq  the  data  elements  definitions,  (2) 
Maintaininq  the  attributes  of  fields,  (3> 

Reducinq  the  data  redundancies  and 
inconsistencies,  (4)  Allowinq  module  desiqners 
to  communicate  effectively  with  each  other 
throuqh  joint  meetinqs  prior  to  chanqinq  the  data 
base,  (5)  Containinq  cross  references  of  users  of 
data,  and  (6)  Determininq  the  impact  of  data  base 
chanqes  on  the  data  base  and  other  modules. 

Build  Plan.  A  "build"  is  a  loqical  collection 
of  modules.  Modules  are  desiqnated  as  part  of  a 
build,  tested  as  modules,  then  inteqrated  into 
builds.  Build  1  may  have  modules  1,3, 5,8.  Build 
5  is  modules  1,2, 3, 5, 8.  Build  2  is  not  dependant 
on  completion  of  build  1;  however  a  certain 
level  of  completion  must  be  achieved  prior  to 


the  modules  beinq  used  in  build  2.  Each  build 
adds  modules  with  phased  inteqration  until 
the  complete  product  is  achieved.  The  build 
plan  is  the  desiqn  of  this  process*  and  is 
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Fiqure  8.  Summary  of  Computer  Proqram  Desiqn 
Aonroach  [Ref  .  •  n  .  R-Rl 


maintained  by  the  manaqer  responsible  for  the 
software  development  and  is  updated  as  required. 
Computer  Program  Implementation  Phase 
The  implementation  phase  is  actually  made  up  of  two 
sub-phases;  the  detailed  desiqn  phase,  and  the  code  and 
debuq  phase. 

Detailed  Desiqn  Phase: 

-  Objectives:  After  successful  review  of  the  hiqh- 
level  module  desiqns,  the  detailed  desiqn  of  each 
module  is  bequn.  The  data  desiqn*  tables*  variables* 
flaqs*  indicies*  data  base  references*  I/O  formats* 
required  system  library  routines*  conditions  for 
initiation*  module  limitations*  and  interface 
descriptions  are  defined.  Each  of  the  module 
requirements  identified  in  the  PDS  must  be  desiqned 
into  the  module. 

-  Documentation: 

-  Program  Description  Document  (PDD).  Provides 
a  complete  technical  description  of  all  module 
functions,  structures,  operational  environments, 
operatinq  constraints*  and  private  data  base 
orqani zat ion ,  for  each  module  of  the  element 
computer  proqram.  Each  module  is  described  in  its 
own  volume  of  the  PDD  with  referenced  appendixes 


as  computer  printout  listings.  The  PDD  describes 


and  completely  defines  the  basic  loqic  and  proqram 
procedures  for  each  application  module.  As  a 
detailed  description  of  the  module  structure*  the 
PDD  serves  as  the  essential  instrument  for 
subsequent  use  by  operational  maintenance  and 
contractor  personnel  diaqnosinq  troubles*  makinq 
adaption  chanqes*  desiqninq  and  implementinq 
modifications  to  the  system*  and  in  addinq  new 
functions  to  the  completed  proqram. 

~  Data  Base  Design  Document.  Described  earlier. 

-  Module  Development  Folder  (MDF).  The  MDF  for  each 
module  is  bequn  after  the  internal  desiqn  review* 
and  is  maintained  by  the  coqnizant  programmer  durinq 
all  phases  of  the  module  development  and  test.  Items 
contained  in  the  MDF  include:  (1)  Results  of  the 
internal  desiqn  review,  (8)  Evidence  of  approval 
to  proceed  to  the  next  phase,  (3)  Resolution  of 
action  items,  (A)  Data  describinq  the  rational  for 
the  module  desiqn*  (5)  The  indented  source  listinq 
qenerated  by  A5CP*  <6>  Results  of  the  structured 
wal k-throuqh ,  (7)  Description  of  the  module  for 
the  PDD*  (8)  Unit  test  plan  and  procedure*  and 
(9)  Unit  test  results. 


Code  and  Debug  Phase . 


After  the  detailed  desiqn  is  completed  and 


approved*  the  code  and  debuq  of  the  module  beqins  as 
shown  in  Fiqure  9.  The  pr oqr ammer /ana  1 yst ( s )  qenerates 
source  code  that  satisfies  the  detailed  desiqn  of  the 
module.  Module  and  data  base  codinq  is  considered 
complete  when  a  clean*  error  free  compile  is  achieved 
and  the  Automated  Source  Code  Processor  (ASCP)  computer 
proqram  has  verified  adherence  to  structured  proqramminq 
standards  and  conventions.  Other  than  updatinq  the  MDF , 
there  are  no  additional  documents  produced  durinq  this 
portion  of  the  implementation  phase. 
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Fiqure  9.  Code  and  Debuq  Process  CRef.  5:p.  4-8] 
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-  Computer  Program  Testing  Phase. 

-  Objectives:  This  phase  actually  spans  the 

implementation  phase  and  its  own  phase.  Testinq  is 
divided  into  three  distinct  subphases,  the  unit  test, 
the  build  test,  and  the  proqram  qualification  test. 
Testinq  starts  with  the  smallest  operatinq  component, 
and  develops  throuqh  successively  more  complex  and 
inclusive  staqes.  The  modules  are  integrated  into 
subprogram  builds  which  are  operational  subsets  of 
the  complete  proqram.  Build  level  tests  are  performed 


on  these  inteqrated  builds  to  validate  functional 
capabilities.  Additional  functional  capabilities  are 
successively  added  to  the  subprogram  builds  andi  in 
the  last  staqe,  the  final  build  is  tested  as  a 
complete  proqram.  Naval  participation  in  all  aspects 
of  the  testinq  phase  is  required.  Additionally 
Internal  Proqram  Reviews  are  held  to  qain  joint  Navy > 
contractor,  and  subcontractor  aqreement  with  test 
definitions,  content,  methodoloqy,  performance,  and 
evaluation  for  build  and  qualification  tests. 

Unit  Test  Plan:  The  unit  test  plan  is  contained  in  the 
MDF.  It  contains  the  strateqy  to  exercise  all  of  the 
code  in  the  module,  either  in  a  standalone 
environment,  or  in  an  inteqrated  environment  with 
previously  tested  modules.  Any  failure  is  documented 
in  an  action  item,  which  is  included  in  the  MDF  and 
returned  to  the  proqrammer  for  correction.  Also  a  part 
of  the  unit  test  plan  is  the  unit  test  procedure.  Unit 
test  procedures  are  derived  from  the  unit  test  plan, 
and  corresponding  design  documentation.  They  present 
detailed  instructions  for  test  setup,  execution,  and 
evaluation  of  test  results.  The  unit  test  procedure 
also  becomes  part  of  the  MDF. 


1.  A  definition  of  the  testinq  proqram  and  strateqy 
required  to  test  the  buildt  includinq  a  rational 
for  for  the  testinq  proqram  as  it  relates  to  the 
functional  capabilities  and  structure  of  the  build. 

2.  An  outline  of  the  capabilities  of  the  build  to  be 
tested*  plus  those  capabilities  provided)  but  not 
tested)  and  capabilities  previously  tested  that 
require  retest. 

3.  A  description  of  the  test  methods*  test  tools*  and 
observations  and  measurement  techniques  to  be  used. 

4.  A  specification  of  the  test  sequence. 

5.  A  description  of  the  contents  of  the  test* 
includinq  personnel  requirements*  responsibilities* 
and  facilities  required. 

6.  Detailed  instructions  for  test  setup*  execution* 
and  evaluation  of  test  results. 

7.  A  description  of  the  scenario(s)  which  demonstrate 
the  major  operational  capabilities  of  the  build. 

Proqram  Qualification  Testinq.  Proqram  qualification 
testinq  is  performed  at  the  Computer  Proqram  Test  Site 
and  is  the  final  staqe  of  the  computer  proqram 
development  phase.  Here  the  build  test  plans  and 
procedures  come  toqether  with  the  PPS,  the  IDS*  the 
preliminary  user’s  manual*  and  the  preliminary 
operators  manual  to  qenerate  the  Proqram  Qualification 
Test  Plan  and  Procedures.  Upon  completion  of  the 


testinq  the  Proqram  Packaqe  and  the  Operator’s  Manual 
are  delivered  for  operational  use.  Products  of  this 
phase  are  the  Proqram  Qualification  Test  Report  and 
the  Test  Discrepancy  Report. 

Fiqure  11  summarizes  the  relationships  between  the 
required  software  documents  and  software  phases. 
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Fiqure  11.  Relat ionsh ips  Between  Software  Documents  and 
Software  Phases.  CRef.  6:p  4023 


IV.  NAVAL  DOCUMENTATION:  PROBLEMS  AND  SOLUTIONS 


A.  NAVAL  DOCUMENTATION,  HOW  DOES  IT  STACK  UP? 

Whan  viewinq  the  Navy  Military  Standard  for  Software 
Development,  D0D-STD-1679A(Navy ) ,  one  cannot  help  but  to  be 
impressed  with  the  very  modern  and  complete  approach  the 
Navy  takes  in  its  software  development.  Usinq  the  DDG-51 
software  desiqn  effort  now  in  proqress,  and  the  CG-41  desiqn 
effort  as  an  example  of  a  major  tactical  embedded  computer 
software  desiqn  proqram,  every  facet  of  modern  software 
desiqn  technoloqy  is  present.  Software  conforminq  to  DQD- 
STD- 1 679A < Navy )  exhibits  the  followinq  characteristics: 

-  A  well  defined  software  methodoloqy  that  includes  a 
defined  life-cycle  model  and  definitive  phases  of  the 
1 ife-cycle. 

-  A  stronq  level  of  planninq  in  the  System  Definition  and 
Desiqn  Phase  which  is  exceptionally  well  documented 
throuqh  the  System  Requirements  (A  Spec),  and  Element 
Requirements  <B1  Spec). 

-  Early  definition  of  the  Computer  Proqram  Performance 
Requirements  documented  in  the  PPS  and  early  definition 
of  interfaces  documented  in  the  IDS. 

-  Modular  computer  proqram  desiqn  specified  in  the  PDS 
with  additional  updates  to  the  IDS  and  further 
documented  in  the  PDD  and  DBDD. 

-  A  stronq  formal  conf iqurat ion  manaqement  plan  that  is 
enacted  early  in  the  desiqn  phase  to  maintain  a 
definitive  version  of  the  project  throuqh  all  phases, 
and  manaqed  by  a  separate  conf iquration  manaqement 
qroup . 

-  Early  definition  of  performance  requirements  directly 
translated  into  test  plans  and  procedures. 


-  A  hiqhly  structured  test  plan  that  includes  test 
requirements •  test  proceduresi  definitive  metrics  for 
the  test  included  in  the  test  specification,  test 
documentation  procedures  for  conduct inq  the  test, 
procedures  for  recordinq  the  results  and  qaininq 
approval,  and  a  cyclic  approach  to  correction  of  errors 
detected . 

-  A  quality  assurance  proqram  that  incorporates  all 
aspects  of  the  testinq,  with  a  seperate  QA  team. 

-  A  software  methodoloqy  that  is  desiqned  to  smoothly 
produce  the  documents  required  as  a  function  of 
followinq  the  prescribed  methodoloqy. 

-  Standardized  document  content  and  desiqn  as  specified  in 
data  item  descriptions  (DIDs)  enacted  in  the  contract. 

-  A  well  controlled  review  procedure  as  part  of  the 
methodoloqy  that  ensures  the  "riqht  product  is  beinq 
built",  and  that  the  "product  is  beinq  built  riqht",  and 
ensures  that  the  Navy  is  well  informed  and  in 
concurrance  with  the  contractor  in  all  phases  of  the 
pro ject . 

Additionally,  the  software  development  methodoloqy 
utilized,  and  the  documentation  produced  under  DOD-STD- 
1 679A ( Navy )  meets  or  exceeds  the 

requirements/recommendat ions  of  the  followinq  publications: 

-  National  Bureau  of  Standards  (NBS)  Federal  Information 
Processinq  Standards  (FIPS)  Publications  3B  and  64, 
Guidelines  for  Documentation  of  Computer  Proqrams  and 
Automated  Data  Systems,  Guidelines  for  Documentation  of 
Computer  Proqrams  and  Automated  Data  Systems  for  the 
Initiation  Phase,  respectively. 

-  National  Bureau  of  Standards,  Special  Publication  500 
-15,  Documentation  of  Computer  Proqrams  and  Automated 
Systems.  A  symposium  held  at  NBS  in  1976  to  discuss  the 
problems  in  documentation  of  computer  proqrams.  All 
problems  addressed  in  this  symposium  and  listed  in  the 
publication  are  addressed  in  D0D-STD-1679A(Navy ) . 

-  Institute  of  Electrical  and  Electronics  Enqineers  (IEEE) 
Standard  for  Software  Test  Documentation,  IEEE  Std  8E9 
-1983.  Althouqh  the  terminoloqy  differs  somewhat,  the 
major  provisions  of  the  IEEE  standard  are  covered  well 


in  D0D-STD-1679A(Navy > 


-  National  Bureau  of  Standards  Special  Publication  500 
-106,  Guidance  on  Software  Maintenance.  An  important 
note  here  is  that  the  Navy’s  definition  of  maintenance 
and  that  of  the  NBS  differ.  Whereas  the  NBS  terms  any 
chanqes  to  the  code  after  the  approval  of  the  oriqinal 
baseline  as  maintenance  (termed  perfective  and  adaptive 
maintenance),  the  Navy  considers  modifications  and 
additions  of  enhancments  to  the  oriqinal  baseline  as 
further  development.  However,  the  provisions  of  NBS 
Special  Publication  500-106  for  perfective  and  adaptive 
maintenance  are  included  in  DQD-STD-1679A(Navy ) . 


B.  NAVAL  DOCUMENTATION,  THE  PROBLEM  AND  CAUSES 

Althouqh  software  developed  and  documented  in  accordanc 
with  D0D-STD-1679A(Navy )  and  the  associated  envoked  DIDs 
would  appear  to  utilize  what  is  presently  considered  to  be 
the  most  modern  and  effective  software  development 
methodoloqies,  and  to  provide  documentation  that  meets  the 
provisions  and  requirements  of  all  authoritative 
publications  there  are  still  major  problems  expressed  by 
personnel  associated  with  naval  software  development. 
However,  the  cause  of  the  problems  do  not  appear  to  be  as  a 
result  of  discrepancies  in  the  applicable  standards,  but 
rather  the  problems  appear  to  be  as  a  result  of  manaqement 
improperly  viewinq  the  reasons  for  documentation  and  not 
placinq  the  appropriate  priority  on  the  documentation 
process . 

One  problem  noted  is  the  possibility  of  "over- 
documentinq"  a  project.  Documentation  is  an  expensive 
undertakinq,  and  it  is  money  "up  front",  that  is  money  that 


is  required  early  in  the  project’s  life-cycle.  Additionally* 
modifications  to  the  software  made  in  the  later  phases 
require  that  the  project  qo  back  and  update  all  of  the 
documentation  affected  by  the  chanqe.  This  is  always  a  major 
expense.  The  more  complex  the  level  of  the  affected 
documentation  then  the  more  expensive  the  modifications 
become.  Dr.  Sinqh  of  Naval  Material  Command  08Y  expressed  in 
an  interview  a  stronq  belief  that  many  of  the  smaller 
tactical  software  projects  are  over  documented*  or  that  the 
documentation  level  is  much  too  complex  for  the  scope  of  the 
project.  He  proposes  that  one  of  the  first  actions  of  the 
project  manaqement  is  to  determine  exactly  what 
documentation  level  is  desired  based  on  the  criticality  of 
the  project*  the  size  of  the  project,  its  planned  life-span, 
and  the  probability  of  chanqes  beinq  made  in  the  oriqinal 
requirements  specification.  His  view  is  supported  in  FIPS 
PUB  38  which  defines  four  levels  of  documentation  [Ref.  4: 
pp .  10-111.  However  Dr.  Sinqh  feels  that  even  if  the 
software  is  "critical",  which  would  place  it  in  the  hiqhest 
level  of  FIPS  PUB  38  documentation,  there  is  some  room  for 
makinq  the  documentation  a  bit  less  complex.  Ulhile  too 
little  documentation  normally  brinqs  about  major  expense 
later  on  in  the  life-cycle,  too  much  documentation  acts  as 
an  unnecessary  burden  and  expense  throuqhout  the  life-cycle. 

Another  problem  evolves  from  the  Navy’s  commitment  to 
the  phased  life-cycle  approach.  The  phased  life-cycle 


approach  does  not  provide  for  chanqes  beinq  made  in  products 
of  phases  already  past  such  as  the  requirements 
specification  beinq  chanqed  when  the  project  is  in  the 
testinq  phase.  If  a  chanqe  occurs  then  the  only  way  the 
chanqe  can  be  accommodated  is  to  back  up  to  the  last  phase 
that  would  not  be  affected  by  the  chanqe  and  start  over  with 
the  development  process  at  that  point  incorporating  the 
chanqe  as  the  project  flows  throuqh  the  phases.  This  is  an 
expensive  and  time  consuminq  method  to  accommodate  chanqe 
but  it  is  the  only  method  that  will  ensure  success  when 
usinq  the  phased  life-cycle  approach. 

The  most  siqnificant  problem  expressed  concerninq 
documentation  of  naval  tactical  software  projects  was  a  lack 
of  understand inq  of  what  purpose  the  documentation  is  to 
serve.  Documentation  serves  two  major  purposes;  (1)  to 
interact  with  the  software  methodoloqy  used  in  providinq  a 
quide  for  accomplishment  of  the  project*  a  set  of  wickets  if 
you  will,  for  the  engineers  to  pass  throuqh  on  their  way  to 
accomp 1 ish inq  their  qoals,  and  (2)  to  historically  record 
the  qoals  or  requirements  of  the  system,  and  the  processes 
and  methods  used  to  achieve  those  requirements  as  a  basis 
for  understandinq  the  system  in  order  to  be  able  to  modify 
the  system  in  the  future.  D0D-STD-l679A(Navy )  provides  a 
fairly  qood  methodoloqy  outline  for  software  desiqn  of  a 
naval  tactical  system.  It  also  provioes  an  excellent 
description  of  what,  historically,  have  proven  to  be  useful 


documents  to  both  the  desiqner  and  the  maintainer.  What  it 
does  not  provide  is  an  understanding  of  how  important 
documentation  is  to  the  software  development  effort  or  how 
important  documentation  is  to  the  continual  success  of  the 
project  in  the  face  of  change.  Documentation  is  an  inteqral 
part  of  planninq  and  controlling  the  software  development. 
Each  document  represents  a  milestone  in  the  further 
reduction  of  top  level  requirements  into  accomplishable 
tasks.  It  is  the  tanqible  portion  of  the  methodoloqy  that 
functions  as  a  control  tool  for  manaqement  throughout  the 
life-cycle  of  the  software.  And  it  allows  the  product  to  be 
enhanced  or  otherwise  modified  in  the  future  by  individuals 
not  oriqinally  associated  with  the  development  effort. 
Management  must  realize  this  as  such  and  enforce  the 
discipline  necessary  to  produce  or  update  the  documentation. 

Many  of  the  individuals  interviewed  for  this  thesis 
expressed  a  concern  that  the  documentation  for  their  project 
was  either  non-ex istant ,  very  late,  or  not  up  to  date  with 
the  actual  state  of  the  project.  Documentation  that  is  not 
up  to  date  is  in  many  cases  worse  than  non-existant 
documentation  in  that  it  has  the  possibility  of 
misrepresenting  the  system.  Documentation  that  is  late 
normally  turns  into  documentation  that  is  not  up  to  date.  Ir 
most  software  design  methodologies  documentation  is  used  to 
provide  a  measure  of  what  the  system  goals  are,  and  where 
the  system  is.  If  there  is  nothing  that  provides  a 


definitive  answer  of  where  the  system  is*  then  it  is  quite 


difficult  to  say  where  the  system  is  qoinq. 

Althouqh  an  excellent  outline  of  what  documentation  to 
consider  is  provided  in  DQD-STD-1679A(Navy >  and  most 
projects  commence  with  an  excellent  plan  for  documentinq 
their  systems*  the  latter  staqes  of  a  larqe  portion  of  these 
projects  find  themselves  with  documenatat ion  that  is 
inaccurate  or  behind  schedule.  NBS  Special  Publication  500- 
87  CRef.  71  provides  five  main  reasons  for  this  happeninq: 

-  Low  Priority  for  Documentation.  Project  manaqement  does 
not  encouraqe  the  system  analysts  and  desiqners  to 
maintain  and  update  their  documentation  when  faced  with 
time  schedules  and  limited  resources. 

-  Lack  of  Resources.  Low  priority  for  documentation  often 
leads  to  inadequate  resources  to  perform  necessary 
documentation  tasks.  The  "we’ll  qet  to  it  when  we  have 
time  and  money"  syndrome  takes  effect. 

-  Lack  of  Planninq.  Manaqement  fails  ♦.o  clarify 
documentation  requirements  at  the  start  of  the  project. 

-  Failure  to  Specify.  Manaqement  fails  to  adequately 
specify  the  system  requirements  at  the  start  of  the 
pro  ject . 

-  Personnel  Attitudes.  Proqrammers  often  have  little 
interest  in  documentinq.  The  work  is  often  viewed  as 
unqlamorous*  and  daily  pressures  often  override  some 
perceived  uncertain  needs  for  documentation. 
Documentation  is  not  visable;  as  lonq  as  the  project  can 
move  alonq  then  documentation  is  viewed  as  unneeded  and 
priorities  often  shift  to  more  visable  objectives. 


C.  DOCUMENTATION,  A  SOLUTION  IN  ITSELF 

Documentation  must  not  be  viewed  as  a  necessary  evil  in 
a  software  project,  but  rather  as  a  vital  manaqement  tool  to 


be  used  in  controlling  the  entire  project.  Management  must 
realize  that  documentation  is  a  major  key  to  a  successful 
project.  "In  order  to  yield  a  good  software  product >  the 
software  documentation  activities  must  be  integrated  into 
the  whole  software  development  process.  Program 
documentat ion  is  an  active  part  of  program  development.  It 
should  not  be  treated  as  a  passive  task  of  simply 
recapturing  the  descriptions  of  an  already  developed 
program.  Good  program  design  leads  to  good  documentation. 
Good  documentation  contributes  to  good  design."  CRef.  91 
Viewing  the  causes  of  poor  documentation  mentioned  in 
section  B  above,  naval  tactical  software  projects  appear  to 
suffer  from  only  three  of  the  five  causes.  There  is  neither 
a  lack  of  planninq  nor  a  failure  to  specify  initial 
reguirements .  In  fact,  naval  tactical  software  projects 
place  a  high  priority  on  initial  planning  and  specifying  the 
initial  reguirements  of  the  project.  Unfortunately*  despite 
a  seemingly  high  priority  being  placed  on  documentation  as 
evidenced  by  the  strong  discussion  of  documentation  in  DOD- 
STD-1679A(Navy )  and  the  associated  DIDs*  documentation 
appears  to  be  guickly  placed  on  the  "back  burner"  when 
confronted  with  deadline  dates  and  unplanned  modif ications. 
These  actions  betray  a  relatively  low  priority  being  placed 
on  documentation.  Additionally*  when  faced  with  funding 
limitations  and  unplanned  modifications*  updating 
documentation  is  again  assigned  a  low  priority*  thus 


becominq  late  or  incomplete  which  complicates  the  project 
later  in  its  life-cycle  when  qood  documentation  is  required 
for  additional  modifications  or  improvements.  Personnal 
attitudes  deqradinq  the  quality  of  naval  tactical  software 
documentation  more  difficult  to  substantiate  throuqh  naval 
sources.  The  Navy  normally  contracts  out  the  vast  majority 
of  its  proqramminq  and  desiqn  with  a  substantial  approval 
end  testinq  process  to  maintain  control  of  the  project. 
However  a  siqnificant  number  of  studies  have  concluded  that 
proqrammers  have  neither  the  desire  nor  the  exact  talents  to 
properly  document  a  project  CRef.  9],  so  it  can  be  safely 
assumed  that  naval  contractors  suffer  from  the  same 
problems. 

The  solution  to  these  problems  must  take  on  a  two 
pronqed  approach.  One  must  be  the  responsib i 1 ty  of  the 
contracted  corporations,  the  other  a  responsibility  of  naval 
tactical  software  manaqement. 

There  is  presently  quite  a  larqe  amount  of  research  and 
development  beinq  peformed  in  the  areas  of  automated  tools 
for  the  documentation  effort.  With  the  ever  increasinq  power 
of  computers,  and  the  simultaneous  demand  for  systems  to 
take  advantaqe  of  the  developments  in  computers  and  to  do 
more*  the  complexity  of  the  major  systems  beinq  produced 
today  has  outstripped  the  ability  of  the  system  analysts 
without  the  assistance  of  automated  tools.  The  time  has 
passed  when  a  desiqner  can  effectively  review  module 


performance  requirements  and  say  with  certainty  that  they 
meet  the  top  level  requirements.  There  is  simply  too  much 
for  an  individual  to  handle.  Additional ly»  maintaininq  data 
dictionaries!  data  flow/control  flow  diaqramsi  interface 
specifications!  and  the  liket  has  aqain  become  much  too 
complex  for  the  unassisted  individual.  Althouqh  beyond  the 
scope  of  this  thesisi  it  stronqly  recommended  that  naval 
manaqersi  when  evaluatinq  a  contractor’s  response  to  request) 
for  proposals!  take  into  account  the  contractor’s  ability  to 
produce  the  proper  documentation  completely  and  on  time  and 
their  ability  to  maintain  this  documentation  in  the  event  of 
unplanned  chanqes.  Manaqers  should  consider  what  tools  are 
beinq  employed  by  the  contractor  and  whaty  if  any, 
documentation  orqanization  is  proposed  by  the  contractor. 

The  second  half  of  the  two  pronqed  approach  is  the 
responsibility  of  naval  tactical  software  manaqement .  First 
and  foremost  manaqement  must  realize  the  importance  of 
quality!  timely  documentation  to  the  projects  success. 
Documentation  must  be  moved  from  the  back  to  the  front 
burner.  This  can  be  done  by  simply  makinq  documentation  a 
factor  in  which  the  quality  of  the  contract  is  judqed.  That 
isf  subject  documentation  delivered  to  a  metrics  evaluation! 
the  performance  of  which  determines  a  portion  of  payment  on 
the  contract.  A  contractor  faced  with  a  loss  of  revenue!  or 
a  qain(  as  determined  by  the  quality  of  his  documentation 


performance  will  certainly  raise  documentation  in  his 
prior i t ies . 

Additionally,  management  should  consider  the  formation 
of  a  Documentation  Group  on  a  management  level  par  with  that 
of  the  Quality  Assurance,  and  Configuration  Management 
groups.  Although  the  idea  of  a  documentation  committee  is 
not  new,  a  documentat ion  group  would  be  formed  at  the 
beginning  of  the  project  and  relieve  QA,  CM,  and 
designers/analysts  of  the  burden  of  documentation  decisions, 
not  formed  to  review  the  already  present  problems  in 
documentation  as  most  committees  are.  A  documentation  group 
could  be  charged  with  the  responsibility  to: 

-  Recommend  reguired  documentation  and  document  complexity 
for  the  project. 

-  Evaluate  a  contractor’s  ability  to  produce  reguired 
documentation. 

-  Establish  metrics  with  which  the  contractor’s 
documentation  performance  could  be  judged. 

-  Perform  auditing  functions  to  verify  documentation 
accurately  reflects  the  system  beinq  produced. 

-  Work  with  QA  and  CM  in  maintaining  documentation. 

-  Collect  cost  versus  benefits  data  on  documentation  to 
analyze  for  use  in  future  projects. 

-  Provide  a  group  of  individuals  whose  major  concern  is 
that  of  proper  documentation  of  systems  and  maintenance 
of  that  documentation. 

Whether  a  formal  documentation  group  is  established  or 
not,  the  importance  of  high  guality  timely  documentation  as 
a  critical  portion  of  a  successful  project  must  be  impressed 


upon  the  entire  development  team.  The  responsibilities 
recommended  above  for  the  proposed  documentation  qroup  must 
be  fulfilled  no  matter  what  the  orqani zat ional  distribution 
is.  Documentation  must  be  maintained  throuqhout  the  entire 
life-cycle  and  must  receive  a  priority  equal  to  that  of  the 
desiqn  and  code  function  itself.  If  a  documentation 
requirement  is  delayed  in  order  to  be  able  to  meet  some 
unforseen  requirement,  then  manaqement  must  make  every 
effort  to  ensure  that  the  documentation  is  completed  as  soon 
as  feasible  and  not  allowed  to  be  continually  delayed.  The 
problems  caused  as  a  result  of  late  documentation  increase 
proportionately  with  the  amount  of  delay  involved. 
Additionally  a  direct  correlation  between  the  size  and 
complexity  of  the  proposed  system  and  that  of  the 
documentation  must  be  established,  the  amount  of 
documentation  and  the  complexity  must  be  critically  reviewed 
at  the  start  of  a  project  and  recorded  in  the  contract 
requirements . 

The  old  adaqe  "the  job  isn’t  done  until  the  paper  work 
is  completed"  is  a  most  important  rule  of  thumb  to  remember 
when  manaqinq  a  software  development  project. 


V.  SUMMARY  OF  CONCLUSIONS 


This  thesis  has  reviewed  the  methodoloqy  used  in  the 
development  of  Navy  tactical  embedded  computer  software  and 
the  documentation  produced  by  followinq  this  methodoloqy. 
The  major  conclusions  are  presented  in  the  followinq 
paraqraphs . 

The  methodoloqy  utilized  by  the  Navy  was  compared  to 
those  recommended  by  the  National  Bureau  of  Standardsi  the 
IEEE*  commercial  publications*  academic  publications*  and 
experienced  individuals.  Comparison  revealed  that  the  Navy 
utilizes  an  extremely  modern*  complete*  and  efficient 
methodoloqy  that  incorporates  most  all  of  the  suqqested 
development  procedures. 

The  Navy*  in  developinq  a  new  combat  system*  or  in 
modifyinq  an  existinq  system*  normally  acts  as  a  manaqement 
team  that  contracts  out  explicit  software  desiqn  to  a 
contractor  throuqh  competitive  bids.  D0D-STD-1679A(Navy ) 
acts  as  the  major  control linq  document  for  Navy  manaqement 
to  use  in  contractor  developed  software.  This  standard 
defines  a  qeneral  methodoloqy  usinq  the  phased  life-cycle 
approach  for  software  development  that  can  be  tailored  to 
the  specific  project  throuqh  the  use  of  data  item 
descr iptions(DIDs) .  The  standard  does  not  address  specific 


development  procedures  such  as  Chief  Programmer  Teams,  or 


technical  writers,  but  rather  it  defines  the  output  desired 
by  the  Navy  and  characteristics  this  output  must  exhibit  for 
the  product  to  be  satisfactory .  Items  the  product  must 
exhibit  include  top-down  desiqn.  modularity,  bottom-up 
testinq.  etc..  The  major  controlling  functions  utilized  in 
this  standard  are  a  stronq  interaction  between  contractor 
and  the  Navy,  specific  divisions  where  Navy  approval  is 
required  for  further  development,  and  extremely  specific 
documentation  requirements  that  would  normally  be  fulfilled 
if  the  contractor  were  followinq  the  provisions  dictated  by 
DOD— STD- 1 679A  <  Navy ) . 

The  DOD— STD- 1 679A ( Navy )  was  found  to  be  entirely 
satisfactory  for  the  purpose  to  which  it  was  desiqned  when 
exercised  by  competent  management. 

The  major  problems  discussed  were  not  caused  by 
deficiencies  in  D0D-STD-1679A.  but  rather  were  caused  by  a 
misinterpretat ion  of  the  standard  by  management.  One  problem 
noted  was  the  propensity  for  smaller  software  development 
projects  to  be  over-documented.  Management  must  determine 
what  the  documentation  level  of  the  system  is  to  be  as  an 
initial  action  and  must  make  this  decision  evident  as  part 
of  the  contract.  Documentation  complexity  and  coverage  must 
be  determined  by  considering  the  projects  size,  complexity, 
and  planned  life-cycle.  Items  such  as  the  possibility  for 
future  modifications,  the  planned  lifetime,  and  the 


61 


criticality  of  proper  performance!  must  be  balanced  aqainst 
the  cost  and  burden  of  proper  documentation.  Tradeoffs  are 
inevitable!  but  a  clear  decision  must  be  reached  in  this 
area . 

Once  a  decision  concerning  the  level  and  complexity  of 
the  documentation  for  the  project  has  been  reached!  the 
decision  must  be  enforced  throughout  the  project’s  life- 
cycle.  Projects  examined  exhibited  characteristic  behavior 
of  early  documentation  being  of  high  quality  and  produced  on 
time  and  within  budqeti  however »  as  modifications  occurred! 
and  time  and  money  limits  became  a  major  factor ( 
documentation  was  quickly  put  aside  in  the  interest  of  a 
fully  functional  program  with  the  added  performance 
functions.  As  documentation  is  an  important  controlling 
feature  of  DQD-STD- 1679A ,  and  poor  documentation  has  a 
"snow-bal 1 inq"  effect  as  the  project  moves  further  down  its 
life-cycle!  it  is  suggested  that  this  not  be  done  so  without 
careful  consideration.  Perhaps  the  modification  is  not  so 
essential!  or  if  it  is  then  every  effort  should  be  made  to 
restore  the  documentation  to  its  high  quality  level  as  soon 
as  possible. 

The  final  conclusion  was  that  management  does  not  place 
a  high  enouqh  priority  on  documentation.  Although  it  was  not 
possible  to  statistically  relate  project  difficulties  to 
inadequate  earlier  documentation!  many  of  those  interviewed 
expressed  a  view  that  their  problems  would  not  be  as 


difficult  had  they  the  proper  documentation  available.  The 
importance  of  configuration  management  and  duality  assurance 
to  a  successful  project  has  become  well  understood.  It  is 
suggested  that  proper  documentation!  and  a  continuous  effort 
along  that  line  throughout  the  life-cycle  be  elevated  to  the 
priorities  now  enjoyed  by  CM  and  QA.  This  thesis  suggested 
the  creation  of  a  documentation  group  egual  in  stature  to 
the  QA  and  CM  groups  to  oversee  the  documentation  process. 
Proper  documentation  is  an  investment  in  the  future 
performance  of  the  software  product i  and  assists  in 
controlling  the  present. 
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